Add VoxCPM v1 — lightweight VoxCPM TTS support (0.5B) - #256

…d weight handling and embedding transpose

Bug: VoxCPM1 model produced pure noise ("elloそ。") instead of speech due to:
1. Synthesized `fusion_concat_proj` weight (Xavier init) treated as learned weight → wrong concat+linear fusion
2. Embedding weight transposed in V1 GGUF: `token_embd.weight` stored as [hidden, vocab] but audio.cpp expects [vocab, hidden]

Fix:
- Add `is_synthesized()` to TensorSource interface to distinguish loaded vs synthesized weights- Implement in TransformingTensorSource for V1 models- Add embedding weight transpose in set_backend_tensor() for `base_lm.embed_tokens.weight`
- Update 5 `has_fusion_proj` checks to exclude synthesized weights
- Test: "This is a test run for the fix" now transcribes as "This is a test." (was pure noise) --> but still wrong.

## Summary
Fixed VoxCPM1 TTS producing pure noise by correcting tensor synthesis and shape validation issues.

## Changes
- **`src/models/voxcpm2/assets.cpp`**: Only synthesize tensors missing from GGUF (not unconditionally). Fixed `feat_encoder.special_token` shape (1D vs 4D). Added relaxed rank handling in `set_backend_tensor()` for V1.
- **`src/framework/assets/tensor_source.cpp`**: Added `relaxed_rank` parameter to `validate_expected_shape()` allowing shape mismatches when element counts match.

## Root Cause
Synthesized (Xavier-initialized) tensors were used instead of learned checkpoint weights. The `is_synthesized()` check now correctly distinguishes true synthesized tensors (only `fusion_concat_proj` for V1) from loaded weights.

## Validation
- VoxCPM1: 16kHz speech, RMS ~0.10-0.15 ✅
- VoxCPM2: 48kHz speech (no regression) ✅
- Embedding transpose: `[1024,73448]` → `[73448,1024]` ✅
- `has_fusion_proj=false` for V1 ✅

## Fix
- Added GGUF metadata reading to `TensorSource` (tokenizer.ggml.*, voxcpm_*)
- Created `VoxCPM1GgufTokenizer` + `load_voxcpm1_config_from_gguf()` for native GGUF loading
- Added `VoxCPM2TokenizerWrapper` for dual JSON/GGUF tokenizer support
- Updated `load_voxcpm2_assets()` to auto-detect/use GGUF metadata
- Removed external JSON deps from `model_specs/voxcpm1.json`

## Test (ASR: sensevoice@11533)
- VoxCPM1 0.5B: "This is a test run for the fix." ❌ (too fask)
- VoxCPM1.5 1.5B: "I the touch for the." ❌ (too slow)

## Remaining Bugs
1. VoxCPM1 too fast (1.28s vs 2.5s) - early stop token
2. VoxCPM1.5 too slow (5.29s vs 2.5s) - arch diff

- config_gguf.cpp: output_sample_rate now falls back to sample_rate (not 16000)
  VoxCPM1.5 GGUF has sample_rate=44100 but no out_sample_rate → was defaulting to 16kHz

- session.cpp: add V1-specific default min_tokens to prevent early stop token trigger
  VoxCPM1 (patch_size=2): min_tokens=20, VoxCPM1.5 (patch_size=4): min_tokens=12
  Without this, stop token triggers at ~2 tokens causing 1.28s cutoff

- Stop predictor weights correctly loaded via V1 relaxed rank (no transpose needed)
  GGUF stores [1024,2] (GGML), expected logical [2,1024] → to_ggml_dims → [1024,2] ✓

Results:
  VoxCPM1 (0.5B): durations scale 1.76s→4.32s with text length
  VoxCPM1.5 (1.5B): durations scale 2.56s→5.12s, correct 44.1kHz sample rate
  VoxCPM2: regression passes (48kHz, 1.28s)

Files: config_gguf.cpp (+6), session.cpp (+14)

…VoxCPM2)**

VoxCPM1 (0.5B/1.5B) models now support voice cloning (`--voice-ref`) and streaming output (`--mode streaming`), matching the VoxCPM2 feature surface. The inference math was already shared; this unblocks the capability/option/reporting layer.

**Root causes fixed (5 gaps):**
- Capability advertisement: now exposes `Tts + {Offline, Streaming}` for V1 (was TTS-only)
- Family identity: `family_impl()` returns `"voxcpm1"` for V1 models (was hardcoded `"voxcpm2"`)
- Session options: `normalize_v1_session_options()` rewrites `voxcpm1.*` → `voxcpm2.*` keys so aliases work
- Request options: added `voxcpm1.*` aliases for all params (`prompt_text`, `min_tokens`, `guidance_scale`, `retry_badcase`, etc.)
- Model spec: `voxcpm1.json` adds `streaming` mode, correct sample rates (16kHz/44.1kHz)

**Changes:** 7 files, +167/−32 lines
- `src/models/voxcpm2/session.cpp` — option normalization, family-aware errors, request-option aliases
- `src/models/voxcpm2/loader.cpp` — capability advertisement, family-labeled errors
- `model_specs/voxcpm1.json` — streaming mode, tags, corrected description
- `docs/tts.md` — V1 streaming/voice-clone examples, `retry_badcase=false` requirement
- `tools/audiocpp_cli/audiocpp_cli_path_cases.json` — 3 new V1 path tests
- `webui/configs/models_catalog.json` + `model_params.json` — V1 WebUI entries

**Verified (CPU):**
| Test | Result |
|------|--------|
| V1 offline TTS | `family=voxcpm1` ✓ |
| V1 voice clone | 16kHz, 5.12s, RMS 0.115 ✓ |
| V1 streaming | 40×1280 chunks, 16kHz ✓ |
| V1 `voxcpm1.*` session/request options | accepted & applied ✓ |
| V1 capability inspection | `modes=offline,streaming` ✓ |
| V2 regression (offline/streaming) | 48kHz, parity maintained ✓ |

Streaming requires `retry_badcase=false` (same as V2, pre-existing design). No V2 behavior changes.

**Issue**: The audio quality is still bad

VoxCPM1 attention used identity longrope factors and a padded stop-token floor. The GGUF's real F32 factor arrays are now read and applied (prefill, stop behavior and duration match the VoxCPM.cpp reference), and the V1 default `min_tokens` is lowered to the reference floor so short utterances are no longer padded with trailing silence.

**Root causes fixed (2):**
- RoPE longrope factors were hardcoded to `1.0f` in the GGUF config path ("GGUF doesn't have native float arrays" was wrong — `GgufTensorSource` already parses them); every attention computation across all four transformers (base LM, residual LM, local encoder, local DiT) used identity positional encodings
- V1 default `min_tokens=20` (per patch_size) vs reference `kMinLen=2` — forced ~1.6s+ of audio and padded short utterances with trailing silence after the stop predictor fired

**Changes:** 2 files, +29/−12 lines
- `src/models/voxcpm2/config_gguf.cpp` — read `voxcpm_lm_config_rope_scaling_{short,long}_factor` f32 arrays via `optional_f32_array()` with size validation (`head_dim/2`), identity fallback only when the keys are absent
- `src/models/voxcpm2/session.cpp` — V1 default `min_tokens = 2` (≡ reference `step > kMinLen`), keeping the `--request-option min_tokens` override

**Verified (CPU, against reference `/workspace/pi/VoxCPM.cpp`):**
| Test | Result |
|------|--------|
| Prefill lm_hidden | l2 within ~2% of reference (was diverged) |
| Stop predictor ("This is a test run for the fix") | fires at pos=19 (was: never fired) |
| Duration | 1.60s (ref 1.68s), trailing silence 0.13s (ref 0.44s) |
| V2 regression | 48kHz output maintained ✓ |
| Embedding + fusion | `[73448,1024]` transpose intact, `has_fusion_proj=false` ✓ |

**Issue**: Voice clone is still not supported — `--task clon` is rejected and passing reference audio + text (`--task tts --voice-ref <wav>`) generates noise rather than cloned speech. Needs a port-audit of the VoxCPM1 reference-audio conditioning path. Full evidence in `docs/reports/2026-08-18_1128_VoxCPM1_RoPE_Longrope_Factors_Stop_Floor_Fix.md`.

…den impl

Restore working voice cloning by fixing the reference-audio conditioning
and AudioVAE encoder alignment against the golden VoxCPM.cpp port:

- generator: only set the CFM `prefix_cond` from prefill rows carrying
  audio (audio_mask). Previously the trailing text row's zero feature
  overwrote the reference patch, feeding the DiT a zero acoustic anchor
  for voice cloning (matches torch feat[:, -1] semantics)
- audiovae: re-enable VAD silence trimming for prompt/reference audio
  (matches golden server_common.cpp:842/878), then pad to patch
  alignment before VAE encoding (left for prompt, right for reference)
- audiovae: drop the `stride % 2` output_padding on the encoder
  downsample conv so causal padding matches the reference encoder
- assets: declare base_lm.embed_tokens.weight as [vocab, hidden] so V1
  GGUFs storing the embedding transposed ([hidden, vocab]) load correctly
- audiovae: add VOXCPM_DUMP_REF_MONO / REF_FEAT / ENC_STAGE debug dumps

Validation (sensevoice-small STT, continuation-mode clone with the Anna
reference): 6/6 target sentences transcribe exactly; text-only TTS
unchanged. Reference-only cloning (ref_start/ref_end tokens) still fails
identically in the golden VoxCPM.cpp - a model-level limitation.

VoxCPM1 voice cloning via `--voice-ref <wav>` produced non-cloned
speech, while `--audio <wav>` (plus `--reference-text`) cloned
correctly. Both flags carried the same user intent, but the CLI mapped
them to different request fields that the session treated as two
distinct audio roles.

**Root cause:** `--voice-ref` set `request.voice->speaker->audio`, which
the session consumed as *reference audio*. For VoxCPM1 the reference
path is wrong in two ways:
- `encode_prompt_audio()` only copies `prompt_text` inside the
  `prompt_audio` branch, so a reference-only request dropped the
  reference transcript entirely (the LM never saw it).
- The reference role right-pads the audio and prepends it wrapped in
  the `<audio_prompt_start/end>` tokens 103/104. Those belong to
  VoxCPM2's "reference-mode plumbing"; the V1 LM was only trained for
  prompt-continuation cloning (golden VoxCPM.cpp uses
  `--prompt-audio` + `--prompt-text`, and its V1 server never calls
  `encode_reference_audio`).

**Fix:** in `VoxCPM2SessionBase::encoded_prompt_for_request()`, when the
model is V1 and only a reference audio is supplied (no `--audio`),
route it through the prompt path — the audio becomes `prompt_audio`
(left-padded, after `<audio_start>`) and `--reference-text` becomes
`prompt_text` (concatenated with the target text). V2 keeps the
reference-mode path untouched. Applies to both offline and streaming
runs (single shared function). Without `--reference-text` the request
now fails with the golden's exact rule ("prompt audio requires
prompt_text or reference_text").

**Changes:** 1 file, +24/−12 lines
- `src/models/voxcpm2/session.cpp` — V1 reference→prompt routing with
  cache key/lookup/encode all using the effective audio roles

**Verified (CPU, 0.5B Q8_0):**
| Test | Result |
|------|--------|
| V1 `--voice-ref` + ref-text | byte-identical WAV to `--audio` + ref-text (same clone) |
| V1 `--voice-ref` without ref-text | clean error (matches golden iff rule) |
| V1 `--audio` regression | byte-identical output |
| V2 `--voice-ref` regression | 48kHz, byte-identical to pre-fix (reference mode preserved) |
| 5-voice clone batch (ana/eric/andrew/jenny/nicole) | 16kHz speech, RMS 0.06–0.08 ✓ |

**Note:** V1.5 (44.1kHz) fails at load with "encoder sample capacity
must be divisible by encoder stride" — pre-existing config gap (stride
1764 ∤ default capacity 240000), identical on `--audio` before this fix.

…main

For fixing VocCPM v1 --voice-ref clone issue

Move VoxCPM GGUF tokenizer/config metadata reading out of the framework
TensorSource interface into a new voxcpm2 GgufMetadataReader. Revert the
validate_expected_shape relaxed_rank parameter and redundant <memory>
include; tensor_source.h/.cpp now differ from upstream/main by a single
line (is_synthesized).

Only the cloned voice is cached across requests; prompt-prefill and
AudioVAE encoder/decoder graphs are freed at request end and rebuilt
fresh on the next request. Idle VRAM drops to ~1.4GB after generation;
very long text may require up to ~3.5GB VRAM during generation.

…main

…r merge

# Conflicts:
#	webui/native/dist/index.html